home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_100 / 134_01 / coro.nro < prev    next >
Text File  |  1985-08-19  |  12KB  |  411 lines
  1. .so AN.NRO
  2. .TH C_CALL 3 "Call a coroutine"
  3. .SH NAME
  4. C_CALL -- Call a coroutine.
  5. .SH SYNOPSIS
  6. .bo
  7. int c_call (fcv, passval)
  8. .ti +5
  9. .bo
  10. struct c_fcv *fcv;   /* FCV of target coroutine */
  11. .ti +5
  12. .bo
  13. int passval;         /* Value to pass to target */
  14. .SH DESCRIPTION
  15. .PP
  16. C_CALL transfers control to a destination coroutine, given its FCV address
  17. and a value to pass.  The destination coroutine's state is restored from
  18. its FCV, and the originating coroutine is recorded as the CALLER of the
  19. target coroutine.
  20. .SH EXAMPLES
  21. .bo
  22. reply = c_call (mailman, &message);
  23. .SH "RETURN VALUE"
  24. .PP
  25. The return value is the value given as "passval" to whatever coroutine
  26. primitive (usually C_DETACH) next invokes the originating coroutine.
  27. .SH "SEE ALSO"
  28. c_caller (3),
  29. c_detach (3), 
  30. c_resume (3),
  31. CORODOC.NRO
  32. .bp
  33. .TH C_CALLBY 3 "Change a coroutine's caller"
  34. .SH NAME
  35. C_CALLBY - Change a coroutine's caller
  36. .SH SYNOPSIS
  37. .bo
  38. c_callby (fcv)
  39. .br
  40. .ti +5
  41. .bo
  42. struct c_fcv * fcv;    /* FCV of new caller */
  43. .SH DESCRIPTION
  44. .PP
  45. C_CALLBY changes the "caller" of the current coroutine to some other coroutine.
  46. When a C_DETACH is executed, it will resume the coroutine specified by "fcv",
  47. not the original caller.
  48. .SH "RETURN VALUE"
  49. The return value is unspecified.
  50. .SH "SEE ALSO"
  51. c_call (3),
  52. c_caller (3),
  53. c_detach (3)
  54. .SH NOTES
  55. .PP
  56. C_CALLBY is needed only in a few esoteric applications and should normally
  57. not be used.
  58. .bp
  59. .TH C_CALLER 3 Find calling coroutine
  60. .SH NAME
  61. C_CALLER -- Find the present coroutine's "caller."
  62. .SH SYNOPSIS
  63. .bo
  64. struct c_fcv c_caller ();
  65. .SH DESCRIPTION
  66. .PP
  67. C_CALLER returns the FCV of the current coroutine's "caller," i.e., the
  68. coroutine which would be invoked by a DETACH.  This is normally the
  69. coroutine that most recently did a C_CALL.
  70. .SH "RETURN VALUE"
  71. .PP
  72. The return value is the FCV address of the "caller" coroutine.
  73. .bp
  74. .TH C_CREATE 3 "Create a coroutine"
  75. .SH NAME
  76. C_CREATE -- Create a coroutine
  77. .SH SYNOPSIS
  78. .bo
  79. struct c_fcv * c_create (functp, stack, info)
  80. .br
  81. .ti +5
  82. .bo
  83. int (*functp)();   /* Initial entry of coroutine */
  84. .br
  85. .ti +5
  86. .bo
  87. int stack;         /* Stack size in bytes        */
  88. .br
  89. .ti +5
  90. .bo
  91. int info;          /* User_supplied information  */
  92. .SH DESCRIPTION
  93. .PP
  94. C_CREATE allocates space for a coroutine's FCV, and creates the coroutine.
  95. The coroutine, when activated via C_CALL or C_RESUME, will enter at the
  96. initial entry point (*functp).  The argument to the function will be the
  97. "passval" word given to C_CALL or C_RESUME.
  98. .PP
  99. The "stack" parameter specifies the number of bytes of stack space given to
  100. the target coroutine.  The "info" parameter specifies the user information
  101. word in the coroutine's FCV; this word may be examined by C_GETINFO or
  102. modified by C_SETINFO.
  103. .SH EXAMPLES
  104. .bo
  105. mailman = c_create (&mailmaid, 1500, &mailbag);
  106. .br
  107. .in +20
  108. .ti -3
  109. /* Create a coroutine, "mailman", which has as
  110. its "main program" the function "mailmaid".  Give
  111. it 1500 bytes of stack, and set its "info" word to
  112. the address of "mailbag". */
  113. .in -20
  114. .SH "RETURN VALUE"
  115. .PP
  116. The return value is a pointer to the FCV of the newly-created coroutine.
  117. If the coroutine cannot be created (due to lack of memory), the symbolic
  118. constant ERROR (-1) is returned.
  119. .SH "SEE ALSO"
  120. c_destroy (3),
  121. c_resume (3),
  122. CORODOC.NRO
  123. .bp
  124. .TH C_DESTROY 3 "Destroy a coroutine"
  125. .SH NAME
  126. C_DESTROY -- Destroy a coroutine.
  127. .SH SYNOPSIS
  128. .bo
  129. c_destroy (fcv)
  130. .br
  131. .ti +5
  132. .bo
  133. struct c_fcv * fcv;
  134. .SH DESCRIPTION
  135. .PP
  136. C_DESTROY destroys a coroutine, and reclaims the space allocated for its
  137. stack and FCV.
  138. .SH CAVEATS
  139. .PP
  140. .ul 1
  141. Never
  142. attempt to resume (with C_CALL, C_RESUME, or C_DETACH) a coroutine which
  143. has been destroyed.  The result is disastrous.
  144. .SH "RETURN VALUE"
  145. The return value is unspecified.
  146. .SH "SEE ALSO"
  147. c_create (3)
  148. .SH MISCELLANEOUS
  149. .PP
  150. C_DESTROY is available only if ALLOC_ON has been #define'd in BDSCIO.H.
  151. Otherwise, the "free" function (which C_DESTROY uses to reclaim unused memory)
  152. will not exist.
  153. .bp
  154. .TH C_DETACH 3 "Detach to the 'caller'"
  155. .SH NAME
  156. C_DETACH -- Detach to the "caller" coroutine.
  157. .SH SYNOPSIS
  158. .bo
  159. int c_detach (passval)
  160. .br
  161. .ti +5
  162. .bo
  163. int passval;     /* Value to be returned */
  164. .SH DESCRIPTION
  165. .PP
  166. C_DETACH returns to the caller coroutine (generally the one that most
  167. recently did a C_CALL), preserving the state of the detached one.
  168. The "passval" parameter will be returned as the value of C_CALL.
  169. .SH CAVEATS
  170. It is an error to try to detach the main C program.
  171. .SH "RETURN VALUE"
  172. .PP
  173. The return value is the "passval" parameter of the next C_CALL or C_RESUME
  174. to the coroutine.
  175. .SH "SEE ALSO"
  176. c_call (3),
  177. c_resume (3),
  178. CORODOC.NRO
  179. .SH DIAGNOSTICS
  180. .bo
  181. Attempt to detach a coroutine (FCV=xxxx) which has no caller linkage.
  182. .PP
  183. The main C program or some coroutine simple RESUMEd by it has attempted to
  184. DETACH.  Since the caller cannot be determined, the program aborts.
  185. "xxxx" is the FCV address of the offending coroutine.
  186. .bp
  187. .TH C_GETINFO 3 "Get coroutine info word"
  188. .SH NAME
  189. C_GETINFO -- Get information word of a coroutine.
  190. .SH SYNOPSIS
  191. .bo
  192. int c_getinfo (fcv)
  193. .br
  194. .ti +5
  195. .bo
  196. struct c_fcv * fcv;   /* FCV address of coroutine */
  197. .SH DESCRIPTION
  198. .PP
  199. C_GETINFO returns the user-specified information word for the designated
  200. coroutine.  This word is initialized by C_CREATE, and can be modified by
  201. C_SETINFO.  It is normally a pointer to a static data area for the 
  202. coroutine's use.
  203. .SH EXAMPLES
  204. .bo
  205. mailbag = c_getinfo (c_wmi ());
  206. .SH "RETURN VALUE"
  207. .PP
  208. The return value is whatever was stored in the "info" word by C_CREATE or
  209. C_SETINFO.
  210. .SH "SEE ALSO"
  211. c_create (3),
  212. c_setinfo (3)
  213. .bp
  214. .TH C_PASSER 3 "Find previous coroutine"
  215. .SH NAME
  216. C_PASSER -- Find coroutine that invoked current one.
  217. .SH SYNOPSIS
  218. .bo
  219. struct c_fcv * c_passer ();
  220. .SH DESCRIPTION
  221. .PP
  222. C_PASSER returns the FCV address of the coroutine that most recently
  223. transferred to the current one by any means (C_CALL, C_DETACH, or C_RESUME).
  224. .SH "RETURN VALUE"
  225. .PP
  226. The return value is the FCV address of the "passer" coroutine.
  227. .SH "SEE ALSO"
  228. c_resume (3)
  229. .bp
  230. .TH C_RESUME 3 "Resume another coroutine"
  231. .SH NAME
  232. C_RESUME -- Resume another coroutine.
  233. .SH SYNOPSIS
  234. .bo
  235. int c_resume (fcv, passval);
  236. .br
  237. .ti +5
  238. .bo
  239. struct c_fcv * fcv;  /* FCV address of coroutine */
  240. .br
  241. .ti +5
  242. .bo
  243. int passval;         /* Value to pass            */
  244. .SH DESCRIPTION
  245. .PP
  246. C_RESUME is the basic means of transferring control among coroutines.
  247. It accepts the FCV pointer of the coroutine to resume, and a parameter
  248. which gives the information to pass to it.  This information is returned
  249. as the value of the transfer function (C_CALL, C_DETACH, or C_RESUME) which
  250. last departed from the target coroutine, or as the argument to the "initial
  251. entry" function if the coroutine is being invoked for the first time.
  252. .SH EXAMPLES
  253. .bo
  254. answer = c_resume (oracle, &question);
  255. .SH "RETURN VALUE"
  256. .PP
  257. The return value is the "passval" parameter of the C_RESUME that eventually
  258. returns to the originating coroutine.
  259. .SH "SEE ALSO"
  260. c_create (3), c_destroy (3),
  261. CORODOC.NRO
  262. .bp
  263. .TH C_SETINFO 3 "Change coroutine's 'info'"
  264. .SH NAME
  265. C_SETINFO -- Change the "info" word of a coroutine.
  266. .SH SYNOPSIS
  267. .bo
  268. int c_setinfo (fcv, info)
  269. .br
  270. .ti +5
  271. .bo
  272. struct c_fcv * fcv;   /* FCV of coroutine */
  273. .br
  274. .ti +5
  275. .bo
  276. int info;             /* New "info" word  */
  277. .SH DESCRIPTION
  278. .PP
  279. C_SETINFO changes the "user specified information" word of the designated
  280. coroutine.  This word, initialized by C_CREATE and examined by C_GETINFO,
  281. is generally a pointerto a static storage area for the coroutine.
  282. .SH "RETURN VALUE"
  283. .PP
  284. The "info" parameter is returned unchanged.
  285. .SH "SEE ALSO"
  286. create (3),
  287. getinfo (3)
  288. .bp
  289. .TH C_TYPE 3 "Type of coroutine invocation"
  290. .SH NAME
  291. C_TYPE -- Find out how current coroutine was invoked.
  292. .SH SYNOPSIS
  293. .bo
  294. int c_type ();
  295. .SH DESCRIPTION
  296. .PP
  297. C_TYPE finds out how the current coroutine was most recently invoked, and
  298. returns a value indicating the type of invocation
  299. .SH "RETURN VALUE
  300. .PP
  301. The return value is one of the following symboli